Skip to main content
POST
/
v1
/
vouchers
/
{code}
/
redemption
Redeem Voucher [Deprecated]
curl --request POST \
  --url https://{cluster}.voucherify.io/v1/vouchers/{code}/redemption \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '{
  "session": {
    "type": "LOCK",
    "key": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts",
    "ttl_unit": "HOURS",
    "ttl": 123
  },
  "customer": {
    "id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv"
  },
  "order": {
    "id": "<string>"
  },
  "metadata": {},
  "options": {
    "expand": [
      "category"
    ]
  }
}'
{
  "id": "r_0c5e8a38730ccec0d5",
  "object": "redemption",
  "date": "2023-01-27T12:34:57.100Z",
  "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
  "tracking_id": "track_9B0kB92+bJa8a+PegaWREw==",
  "metadata": null,
  "amount": 2000,
  "result": "SUCCESS",
  "order": {
    "id": "ord_S4BvUj64TlGqVZDOeud7z3rU",
    "source_id": null,
    "created_at": "2023-01-27T12:34:57.086Z",
    "updated_at": null,
    "status": "PAID",
    "amount": 6000,
    "discount_amount": 2000,
    "total_discount_amount": 2000,
    "total_amount": 4000,
    "applied_discount_amount": 2000,
    "total_applied_discount_amount": 2000,
    "items": [
      {
        "object": "order_item",
        "product_id": "prod_0a9f9ab4ab019a42d5",
        "quantity": 1,
        "amount": 3300,
        "price": 3000,
        "subtotal_amount": 3300
      },
      {
        "object": "order_item",
        "product_id": "prod_0a9f9aeddb019a42db",
        "quantity": 2,
        "amount": 3400,
        "price": 3000,
        "subtotal_amount": 3400
      }
    ],
    "metadata": {},
    "customer": {
      "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "object": "customer"
    },
    "customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "referrer_id": null,
    "object": "order",
    "redemptions": {
      "r_0c5e8a38730ccec0d5": {
        "date": "2023-01-27T12:34:57.100Z",
        "related_object_type": "voucher",
        "related_object_id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
        "related_object_parent_id": "camp_B2Gx83JsSbmvj05MOwxYbNm6"
      }
    }
  },
  "customer": {
    "id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
    "name": "Bob Jones",
    "email": "bob.jones@email.com",
    "source_id": "36_bob",
    "metadata": {
      "age": 26,
      "favorite_brands": [
        "Nike",
        "Adidas",
        "Reebok"
      ],
      "accepts_marketing": false,
      "acquisition_channel": "Facebook"
    },
    "object": "customer"
  },
  "related_object_type": "voucher",
  "related_object_id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
  "voucher": {
    "id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
    "code": "CODE14",
    "campaign": "Gift Card Campaign",
    "campaign_id": "camp_B2Gx83JsSbmvj05MOwxYbNm6",
    "category": "Second",
    "category_id": "cat_0bb343dee3cdb5ec0c",
    "categories": [],
    "type": "GIFT_VOUCHER",
    "discount": null,
    "gift": {
      "amount": 2000,
      "balance": 0,
      "effect": null
    },
    "loyalty_card": null,
    "start_date": "2020-08-16T00:00:00.000Z",
    "expiration_date": null,
    "validity_timeframe": null,
    "validity_day_of_week": null,
    "active": true,
    "additional_info": "secret-code1",
    "metadata": {
      "region": "APAC",
      "season": "Fall"
    },
    "assets": {
      "qr": {
        "id": "U2FsdGVkX1+VibJ6VGxrSVw5qmdbPMP3aP8HfcngMxtQc9Bm649CK1dK36e8YR820Ct26IkvDemEDzV8ozhB3F2BpazbgvCmhAo2Gvmo2WtwBwPh2ISAPJiXQCHRjwmKiqogjqQaNKWLxwDIBUc2jQ==",
        "url": "{{internalVoucherifyURL}}"
      },
      "barcode": {
        "id": "U2FsdGVkX1/GVIi0p5fL5hxAY/ZBmuAU7nYYS03umjd30dwI5v5ZbpNc3Q5MiYbMuIOIT0H2fUTTwd//S4R9AB+60T/x4kSKu3lgfa9KgJmbyrzXm7Ggly06/qph4/asJaZVZIXEba4WJCeHqXCEgg==",
        "url": "{{internalVoucherifyURL}}"
      }
    },
    "is_referral_code": false,
    "created_at": "2022-09-23T11:05:42.164Z",
    "updated_at": "2023-01-27T12:34:57.102Z",
    "validation_rules_assignments": {
      "object": "list",
      "data_ref": "data",
      "data": [],
      "total": 0
    },
    "redemption": {
      "quantity": 18,
      "redeemed_quantity": 1,
      "redeemed_amount": 2000,
      "object": "list",
      "url": "/v1/vouchers/CODE14/redemptions?page=1&limit=10"
    },
    "publish": {
      "object": "list",
      "count": 0,
      "url": "/v1/vouchers/CODE14/publications?page=1&limit=10"
    },
    "object": "voucher",
    "applicable_to": {
      "data": [],
      "total": 0,
      "data_ref": "data",
      "object": "list"
    },
    "inapplicable_to": {
      "data": [],
      "total": 0,
      "data_ref": "data",
      "object": "list"
    }
  },
  "gift": {
    "amount": 2000
  }
}

Authorizations

​
X-App-Id
string
header
required
​
X-App-Token
string
header
required
​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

​
code
string
required

A code that identifies the voucher.

Example:

"2CpRCE2c"

Query Parameters

​
tracking_id
string

A tracking identifier of a user that redeemed a voucher. Identifier generated during voucher validation based on your internal id (e.g., email, database ID). This is a hashed customer source ID. If you also pass a customer ID, the tracking ID must be the ID of a source of the customer object. Otherwise, if you do not pass a customer ID, the tracking you provide must either be a token, like the ones returnee by voucher validation, or a string identifying customer, with the options described below. Although not all information is required, the extra info helps prevent fraud.

Body

application/json

Provide the redemption context in the request body.

  • Discount Code
  • Gift Card
  • Loyalty Card

Request body schema for redeeming a voucher using POST v1/vouchers/{code}/redemption. Redeem a discount code.

​
session
object

Schema model for session lock object. The session object is required to establish a session between multiple parallel validation and redemption requests. If you only send the type parameter in the request, then by default the session lock will be established for 7 days. Read more on establishing a <!-- [validation session](..docs/guides/campaign_recipes/Locking-Validation-Session.md) -->validation session.

​
customer
object

Customer's information. You can pass the unique customer ID that was assigned by Voucherify.

  • Customer ID
  • Customer Source ID
  • Customer
​
order
object

Order information. You can pass the unique order ID that was assigned by Voucherify.

  • Order ID
  • Order Source ID
  • Order Customer And Referrer Ids Objects
​
metadata
object

A set of key/value pairs that you can send in the request body to check against vouchers requiring redemption metadata validation rules to be satisfied. The validation runs against rules that are defined through the <!-- [Create Validation Rules](https://docs.voucherify.io/reference/create-validation-rules) -->Create Validation Rules endpoint or via the Dashboard; in the Advanced Rule Builder → Advanced → Redemption metadata satisfy or Basic Builder → Attributes match → REDEMPTION METADATA. Read more.

​
options
object

Configure parameters returned in the response.

Response

Returns a redemption object if the redeem operation succeeded.

  • Redeem Voucher Response Body
  • Redeem Voucher Response Body
  • Redeem Voucher Response Body

Response body schema for POST v1/vouchers/{code}/redemption. This is an object representing an attempted or successful voucher redemption. This is an object representing a redemption.

Redemption is the key operation in the voucher and promotion tier lifecycle. A customer can redeem a voucher or promotion tier once or multiple times depending on selected limit (quantity). Each redemption is recorded in voucher/promotion's history (redemption_entries). There is also an option to cancel a redemption. We call such operation a <!-- [redemption rollback](OpenAPI.json/paths/~1redemptions~1{redemptionId}~1rollback/post) -->redemption rollback.

​
id
string

Unique redemption ID.

Example:

"r_0bc92f81a6801f9bca"

​
object
string
default:redemption

The type of the object represented by the JSON. This object stores information about the redemption.

​
date
string<date-time>

Timestamp in ISO 8601 format indicating when the redemption occured.

Example:

"2022-10-03T12:24:58.008Z"

​
customer_id
string

Unique customer ID of the redeeming customer.

Example:

"cust_i8t5Tt6eiKG5K79KQlJ0Vs64"

​
tracking_id
string

Hashed customer source ID.

Example:

"track_fxEMFiLowFHg=="

​
metadata
object

The metadata object stores all custom attributes in the form of key/value pairs assigned to the redemption.

​
result
enum<string>

Redemption result.

Available options:
SUCCESS,
FAILURE
​
order
object

Defines the details of the order that is related to the redemption. This is an object representing an order with calculated discounts applied using the voucher code.

  • Order object - Effect: Apply to order
  • Order object - Effect: Apply to items
​
channel
object

Defines the details of the channel through which the redemption was issued.

​
customer
object

Defines the customer that is related to the redemption.

​
related_object_type
enum<string>
default:voucher

Defines the related object.

Related ObjectDefinition
voucherEither a discount voucher, gift card, or loyalty card.
Available options:
voucher
​
related_object_id
string

Unique related object ID assigned by Voucherify, i.e. v_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher.

​
voucher
object

Defines the details of the voucher being redeemed. This is an object representing a voucher with categories and validation rules assignments. This is an object representing a voucher holder. This is an object representing a voucher.

⌘I